home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kopete / kopetemessage.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-14  |  13.6 KB  |  425 lines
  1. /*
  2.     kopetemessage.h  -  Base class for Kopete messages
  3.  
  4.     Copyright (c) 2002-2003 by Martijn Klingens      <klingens@kde.org>
  5.     Copyright (c) 2002-2004 by Olivier Goffart       <ogoffart @ kde.org>
  6.  
  7.     Kopete    (c) 2002-2004 by the Kopete developers <kopete-devel@kde.org>
  8.  
  9.     *************************************************************************
  10.     *                                                                       *
  11.     * This library is free software; you can redistribute it and/or         *
  12.     * modify it under the terms of the GNU Lesser General Public            *
  13.     * License as published by the Free Software Foundation; either          *
  14.     * version 2 of the License, or (at your option) any later version.      *
  15.     *                                                                       *
  16.     *************************************************************************
  17. */
  18.  
  19. #ifndef __KOPETE_MESSAGE_H__
  20. #define __KOPETE_MESSAGE_H__
  21.  
  22. #include "kopetecontact.h"
  23.  
  24. #include <ksharedptr.h>
  25.  
  26. #include <qptrlist.h>
  27. #include <qstring.h>
  28. #include <qdom.h>
  29. #include <qcolor.h>
  30. #include <qfont.h>
  31. #include <qdatetime.h>
  32. #include <qvaluelist.h>
  33.  
  34. #include "kopete_export.h"
  35.  
  36.  
  37. class QDateTime;
  38.  
  39. namespace Kopete {
  40.  
  41.  
  42.   class ChatSession;
  43. class Contact;
  44.  
  45.  
  46. /**
  47.  * @author Martijn Klingens <klingens@kde.org>
  48.  * @author Olivier Goffart <ogoffart @ kde.org>
  49.  *
  50.  * Message represents any kind of messages shown on a chat view.
  51.  *
  52.  * The message may be a simple plaintext string, or a Richtext HTML like message,
  53.  * this is indicated by the @ref format() flag.
  54.  * PlainText message can however have a color, or specific fonts with the flag
  55.  * @ref bg(), @ref fg(), @ref font()
  56.  * It is recommended to use these flags, even for RichText messages, so the user can disable
  57.  * custom colors in the chat window style.
  58.  */
  59. class KOPETE_EXPORT Message
  60. {
  61. public:
  62.     /**
  63.      * Direction of a message.
  64.      * - Inbound: Message is from the chat partner
  65.      * - Outbound: Message sent by the user.
  66.      * - Internal: Messages which are not sent via the network. This is just a notification a plugin can show in a chat view
  67.      * - Action: For the /me command , like on irc
  68.      */
  69.     enum MessageDirection { Inbound = 0, Outbound = 1, Internal= 2 };
  70.  
  71.     /**
  72.      * Format of body
  73.      * - PlainText: Just a simple text, without any formatting. If it contains HTML tags then they will be simply shown in the chatview.
  74.      * - RichText: Text already HTML escaped and which can contains some tags. the string
  75.      *   should be a valid (X)HTML string.
  76.      *   Any HTML specific characters (\<, \>, \&, ...) are escaped to the equivalent HTML
  77.      *   entity (\>, \<, ...) newlines are \<br /\> and any other HTML tags will be interpreted.
  78.      * - ParsedHTML: only used by the chatview, this text is parsed and ready to
  79.      *  show into the chatview, with Emoticons, and URLs
  80.      * - Crypted is used only by Jabber and the Cryptography plugin
  81.      */
  82.     enum MessageFormat{ PlainText = 0x01 , RichText =0x02 , ParsedHTML = 0x04|RichText , Crypted = 0x08|PlainText};
  83.  
  84.     /**
  85.      * Specifies the type of the message.
  86.      * Currently supported types are:
  87.      * - Normal: a message
  88.      * - Action: an IRC-style DESCRIBE action.
  89.      */
  90.     enum MessageType { TypeNormal, TypeAction };
  91.  
  92.     /**
  93.      * Specifies the type of notification that will be sent with this message
  94.      * - Low: almost no notifications. automatically used in groupChat
  95.      * - Normal: Default notification, for normal message
  96.      * - Highlight: Highlight notification, for most important messages, which require particular attentions.
  97.      */
  98.     enum MessageImportance { Low = 0, Normal = 1, Highlight = 2 };
  99.  
  100.     /**
  101.      * Constructs a new empty message
  102.      */
  103.     Message();
  104.  
  105.     /**
  106.      * Deref and clean private object if refcount == 0
  107.      */
  108.     ~Message();
  109.  
  110.     /**
  111.      * Constructs a new message. See @ref setBody() to more information about the format
  112.      * @param fromKC The Contact that the message is coming from
  113.      * @param toKC List of Contacts the message is going to
  114.      * @param body Message body
  115.      * @param direction The direction of the message, Message::Inbound, Message::Outbound, Message::Internal
  116.      * @param format Format of the message
  117.      * @param requestedPlugin Requested view plugin for the message
  118.      * @param type Type of the message, see @ref MessageType
  119.      */
  120.     Message( const Contact *fromKC, const QPtrList<Contact> &toKC, const QString &body,
  121.          MessageDirection direction, MessageFormat format = PlainText,
  122.          const QString &requestedPlugin = QString::null, MessageType type = TypeNormal );
  123.  
  124.     /**
  125.      * Constructs a new message. See @ref setBody() to more information about the format
  126.      * @param fromKC The Contact that the message is coming from
  127.      * @param toKC List of Contacts the message is going to
  128.      * @param body Message body
  129.      * @param direction The direction of the message, Message::Inbound, Message::Outbound, Message::Internal
  130.      * @param format Format of the message
  131.      * @param requestedPlugin Requested view plugin for the message
  132.      * @param type Type of the message, see @ref MessageType
  133.      */
  134.     Message( const Contact *fromKC, const Contact *toKC, const QString &body,
  135.          MessageDirection direction, MessageFormat format = PlainText,
  136.          const QString &requestedPlugin = QString::null, MessageType type = TypeNormal );
  137.  
  138.     /**
  139.      * Constructs a new message. See @ref setBody() to more information about the format
  140.      * @param fromKC The Contact that the message is coming from
  141.      * @param toKC List of Contacts the message is going to
  142.      * @param body Message body
  143.      * @param subject The subject of the message
  144.      * @param direction The direction of the message, Message::Inbound, Message::Outbound, Message::Internal
  145.      * @param format Format of the message
  146.      * @param requestedPlugin Requested view plugin for the message
  147.      * @param type Type of the message, see @ref MessageType
  148.      */
  149.     Message( const Contact *fromKC, const QPtrList<Contact> &toKC, const QString &body,
  150.          const QString &subject, MessageDirection direction, MessageFormat format = PlainText,
  151.          const QString &requestedPlugin = QString::null, MessageType type = TypeNormal );
  152.  
  153.     /**
  154.      * Constructs a new message. See @ref setBody() to more information about the format
  155.      * @param timeStamp Timestamp for the message
  156.      * @param fromKC The Contact that the message is coming from
  157.      * @param toKC List of Contacts the message is going to
  158.      * @param body Message body
  159.      * @param direction The direction of the message, Message::Inbound, Message::Outbound, Message::Internal
  160.      * @param format Format of the message
  161.      * @param requestedPlugin Requested view plugin for the message
  162.      * @param type Type of the message, see @ref MessageType
  163.      */
  164.     Message( const QDateTime &timeStamp, const Contact *fromKC, const QPtrList<Contact> &toKC,
  165.          const QString &body, MessageDirection direction, MessageFormat format = PlainText,
  166.          const QString &requestedPlugin = QString::null, MessageType type = TypeNormal );
  167.  
  168.     /**
  169.      * Constructs a new message. See @ref setBody() to more information about the format
  170.      * @param timeStamp Timestamp for the message
  171.      * @param fromKC The Contact that the message is coming from
  172.      * @param toKC List of Contacts the message is going to
  173.      * @param body Message body
  174.      * @param subject The subject of the message
  175.      * @param direction The direction of the message, Message::Inbound, Message::Outbound, Message::Internal
  176.      * @param format Format of the message
  177.      * @param requestedPlugin Requested view plugin for the message
  178.      * @param type Type of the message, see @ref MessageType
  179.      */
  180.     Message( const QDateTime &timeStamp, const Contact *fromKC, const QPtrList<Contact> &toKC,
  181.         const QString &body, const QString &subject, MessageDirection direction,
  182.         MessageFormat format = PlainText, const QString &requestedPlugin = QString::null,
  183.         MessageType type = TypeNormal );
  184.  
  185.     /**
  186.      * Copy constructor.
  187.      * Just adds a reference, doesn't actually copy.
  188.      */
  189.     Message( const Message &other );
  190.  
  191.     /**
  192.      * Assignment operator
  193.      * Just like the copy constructor it just refs and doesn't copy.
  194.      */
  195.     Message & operator=( const Message &other );
  196.  
  197.     /**
  198.      * Accessor method for the timestamp of the message
  199.      * @return The message's timestamp
  200.      */
  201.     QDateTime timestamp() const;
  202.  
  203.     /**
  204.      * Accessor method for the Contact that sent this message
  205.      * @return The Contact who sent this message
  206.      */
  207.     const Contact * from() const;
  208.  
  209.     /**
  210.      * Accessor method for the Contacts that this message was sent to
  211.      * @return Pointer list of the Contacts this message was sent to
  212.      */
  213.     QPtrList<Contact> to() const;
  214.  
  215.     /**
  216.      * @return the @ref MessageType of this message
  217.      */
  218.     MessageType type() const;
  219.  
  220.     /**
  221.      * @return the view plugin you would prefer to use to read this message. If
  222.      *    null, Kopete will use the user's preferred plugin.
  223.      */
  224.     QString requestedPlugin() const;
  225.  
  226.     /**
  227.      * Accessor method for the foreground color
  228.      * @return The message's foreground color
  229.      */
  230.     QColor fg() const;
  231.  
  232.     /**
  233.      * Accessor method for the background color of the message
  234.      * @return The message's background color
  235.      */
  236.     QColor bg() const;
  237.  
  238.     /**
  239.      * Accessor method for the font of the message
  240.      * @return The message's font
  241.      */
  242.     QFont font() const;
  243.  
  244.     /**
  245.      * Accessor method for the subject of the message
  246.      * @return The message subject
  247.      */
  248.     QString subject() const;
  249.  
  250.     /**
  251.      * Accessor method for the format of the message
  252.      * @return The message format
  253.      */
  254.     MessageFormat format() const;
  255.  
  256.     /**
  257.      * Accessor method for the direction of the message
  258.      * @return The message direction
  259.      */
  260.     MessageDirection direction() const;
  261.  
  262.     /**
  263.      * @brief Accessor method for the importance
  264.      * @return The message importance (low/normal/highlight)
  265.      */
  266.     MessageImportance importance() const;
  267.  
  268.     /**
  269.      * @brief Set the importance.
  270.      * @see importance
  271.      * @param importance The message importance to set
  272.      */
  273.     void setImportance(MessageImportance importance);
  274.  
  275.     /**
  276.      * Sets the foreground color for the message
  277.      * @param color The color
  278.      */
  279.     void setFg( const QColor &color );
  280.  
  281.     /**
  282.      * Sets the background color for the message
  283.      * @param color The color
  284.      */
  285.     void setBg( const QColor &color );
  286.  
  287.     /**
  288.      * Sets the font for the message
  289.      * @param font The font
  290.      */
  291.     void setFont( const QFont &font );
  292.  
  293.     /**
  294.      * @brief Sets the body of the message
  295.      *
  296.      * @param body The body
  297.      * @param format The format of the message, @see MessageFormat
  298.      */
  299.     void setBody( const QString &body, MessageFormat format = PlainText );
  300.  
  301.     /**
  302.      * Get the message body back as plain text
  303.      * @return The message body as plain text
  304.      */
  305.     QString plainBody() const;
  306.  
  307.     /**
  308.      * Get the message body as escaped (X)HTML format.
  309.      * That means every HTML special char (\>, \<, \&, ...) is escaped to the HTML entity (\<, \>, ...)
  310.      * and newlines (\\n) are converted to \<br /\>
  311.      * @return The message body as escaped text
  312.      */
  313.     QString escapedBody() const;
  314.  
  315.     /**
  316.      * Get the message body as parsed HTML with Emoticons, and URL parsed
  317.      * this should be ready to be shown in the chatwindow.
  318.      * @return The HTML and Emoticon parsed message body
  319.      */
  320.     QString parsedBody() const;
  321.  
  322.     /**
  323.      * Get the related  message manager.
  324.      * If it is not set, returns 0L.
  325.      *
  326.      * The @ref ChatSession is only set if the message is already passed by the manager.
  327.      * We should trust this only in aboutToSend/aboutToReceive signals
  328.      */
  329.      ChatSession *manager() const ;
  330.  
  331.      /**
  332.       * set the messagemanager for this message.
  333.       * should be only used by the manager itself
  334.       */
  335.      void setManager(ChatSession *);
  336.  
  337.     /**
  338.      * Enables the use of a background for a message
  339.      * @param enable A flag to indicate if the background should be enabled or disabled.
  340.      */
  341.     void setBgOverride( bool enable );
  342.  
  343.     /**
  344.      * Enables the use of a foreground for a message
  345.      * @param enable A flag to indicate if the foreground should be enabled or disabled.
  346.      */
  347.     void setFgOverride( bool enable );
  348.  
  349.     /**
  350.      * Enables the use of a RTF formatting for a message
  351.      * @param enable A flag to indicate if the RTF formatting should be enabled or disabled.
  352.      */
  353.     void setRtfOverride( bool enable );
  354.  
  355.     /**
  356.      * Return HTML style attribute for this message.
  357.      * @return A string formatted like this: "style=attr"
  358.      */
  359.     QString getHtmlStyleAttribute() const;
  360.  
  361. public:  /* static helpers */
  362.  
  363.     /**
  364.     * Unescapes a string, removing XML entity references and returns a plain text.
  365.     *
  366.     * Note that this method is *VERY* expensive when called on rich text bodies,
  367.     * use with care!
  368.     *
  369.     * @param xml The string you want to unescape
  370.     */
  371.     static QString unescape( const QString &xml );
  372.  
  373.     /**
  374.      * Indicate whether the string is right-to-left (Arabic or Hebrew are bidi locales)
  375.      * or "normal" left-to-right. Calculating RTL on rich text is expensive, and
  376.      * isRightToLeft() therefore uses a cached value.
  377.      */
  378.     bool isRightToLeft() const;
  379.  
  380.     /**
  381.      * @brief Transform a pleintext message to an html.
  382.      * it escape main entity like > < add some <br /> or &nbsp;
  383.      */
  384.     static QString escape( const QString & );
  385.  
  386.  
  387.     /**
  388.      * Helper function to decode a string. Whatever returned here is *nearly guarenteed* to
  389.      * be parseable by the XML engine.
  390.      *
  391.      * @param message The string you are trying to decode
  392.      * @param providedCodec A codec you want to try to decode with
  393.      * @param success Optional pointer to a bool you want updated on success. "Success"
  394.      *    is defined as a successfull decoding using either UTF8 or the codec you
  395.      *    provided. If a guess has to be taken, success will be false.
  396.      */
  397.     static QString decodeString( const QCString &message,
  398.          const QTextCodec *providedCodec = 0L, bool *success = 0L );
  399.  
  400. private:
  401.     /**
  402.      * Message is implicitly shared.
  403.      * Detach the instance when modifying data.
  404.      */
  405.     void detach();
  406.  
  407.     /**
  408.      * Called internally by @ref setBody() and the constructor
  409.      * Basically @ref setBody() without detach
  410.      */
  411.     void doSetBody( const QString &body, MessageFormat format = PlainText );
  412.  
  413.     class Private;
  414.     KSharedPtr<Private> d;
  415.  
  416.     static QString parseLinks( const QString &message, MessageFormat format );
  417. };
  418.  
  419. }
  420.  
  421. #endif
  422.  
  423. // vim: set noet ts=4 sts=4 sw=4:
  424.  
  425.